qsection Introduction {{The jbindings.tcl library is distributed as part of the jstools package. It consists of a number of procedures used by the jbrowser, jedit, jhelp, jmore, jpeople, and jprefs applications. It contains high¡level procedures to set basic and Emacs¡style keyboard bindings for entry and text widgets, as well as the underlying procedures that implement the bindings.
This help file describes jbindings.tcl version 3.6/2.0.
The standard way to use jbindings.tcl is to install it in the Tk library directory (normally /usr/local/lib/tk) and run the auto_mkindex Tcl procedure with appropriate arguments on that directory. You might do this by typing
localhost% wish
wish> auto_mkindex $tk_library "*.tcl"
wish> exit
This lets Tcl automatically find and use procedures from the library when they're called.
However, the jstools applications also allow this library to reside in an individual user's ~/.tk directory. If it's found there, it's sourced when the application first starts running. This lets people who don't have write access to $tk_library at their site install applications using the library for their personal use, and (possibly more importantly) lets them customise the library procedures to their liking.
I strongly suggest that other developers using jbindings.tcl duplicate this behaviour in their applications, using code like the following:
global env
if {[file isfile "$env(HOME)/.tk/jbindings.tcl"]} then {
source "$env(HOME)/.tk/jbindings.tcl"
}
If you've already sourced or auto¡loaded the jlibrary.tcl library, then you can just say
j:source_config jbindings.tcl
instead.
Setting Bindings
Typically, you would then use a variant on the following code to set up class bindings for text and entry widgets:
This assumes that the PREFS(bindings) variable has been appropriately set; you can use j:global_pref_panel and j:read_standard_prefs, both in the jlibrary.tcl library, to allow the user to choose bindings. Note also that you may want to set your own additional application¡specific keyboard bindings depending on the user's preferred keyboard bindings.
A future version of the library will support vi bindings as well.
Some of the code in the library comes from other sources. Some code is based on code from the standard Tk library from the Tk distribution. Other people whose code appears in the library include R. James Noble <kjx@comp.vuw.ac.nz> Paul E. Raines <raines@cgibm1.slac.stanford.edu>, and Tom Phelps <phelps@ginkgo.cs.berkeley.edu>.
Copyright
The library is copyright ⌐ 1992-1994 by Jay Sekora, but may be freely copied and modified for non¡commercial purposes. (Please contact me if you want to use it for a commercial purpose, this may be OK under some circumstances.)}} {{{sel {}} {hilight {}} {xref-topic {}} {xref-section {}} {j:rt:rm {}} {j:rt:it {}} {j:rt:bf {}} {j:rt:bi {}} {j:rt:tt {3.0 4.34 7.213 7.231 7.249 7.280 7.299 7.328}} {j:rt:hl {1.0 2.0 6.0 7.0 9.0 10.0}} {TOPIC:browser.tk {}} {TOPIC:edit.tk {}} {TOPIC:help.tk {}} {TOPIC:more.tk {}} {TOPIC:people.tk {}} {TOPIC:prefs.tk {}} {TOPIC:jedit {}} {TOPIC:jhelp {}} {TOPIC:jmore {}} {TOPIC:jpeople {}} {TOPIC:jprefs {}} {TOPIC:jlibrary.tcl {}} {{SECTION:Procedures to Set Bindings} {}} {{SECTION:Basic Bindings} {}} {{SECTION:Emacs Bindings} {}} {{SECTION:Publically¡Useful Text Procedures} {}}} {{del_from 10.228} {abbrevstart 7.330} {matchend 10.228} {insert 1.0} {del_to 10.228} {anchor 7.326} {matchstart 10.228} {current 1.6}}}
qsection Overview {{Basic Bindings
Emacs Bindings
Procedures to Set Bindings
j:eb:basic_bind Entry set up basic bindings for entry widgets
j:eb:emacs_bind Entry set up Emacs bindings for entry widgets
j:tb:basic_bind Text set up basic bindings for text widgets
j:tb:emacs_bind Text set up Emacs bindings for text widgets
Publically¡Useful Text Procedures
j:tb:mark_dirty mark text widget as dirty (modified)
j:tb:mark_clean mark text widget as clean (unmodified)
j:tb:is_dirty return 1 if text widget is dirty (modified) else 0
The following text bindings are set up by the statement `j:tb:basic_bind Text':
The arrow keys move one character or one line up, down, left or right. The concept of `line' used is that of the text widget (and of Emacs), so a long line that is wrapped in the text widget counts as one line. Also, lines with tabs in them are not currently treated properly.
Home moves to the beginning of the line
End moves to the end of the line
Next scrolls down one screenful. (Next is often labelled PageDown)
This requires that the widget be linked to a scrollbar.
Prior scrolls up one screenful. (Prior is often labelled PageUp)
This requires that the widget be linked to a scrollbar.
Control-i inserts a tab
Control-j inserts a newline
Return inserts a newline
Control-h deletes one character backwards
Delete deletes one character backwards
BackSpace deletes one character backwards
Any other key inserts its ASCII representation
Dragging the mouse past the top or bottom edge of the widget with Button 1 will automatically scroll the widget as it extends the selection. (Thanks to Paul E. Raines <raines@cgibm1.slac.stanford.edu> for code to implement this.)
Dragging the mouse up or down with Button 2 will cause the text widget to scroll, but clicking (quickly) with Button 2 will paste the current X selection. (Thanks to Tom Phelps <phelps@cs.berkeley.edu> for code to implement this.)
Entry Bindings
The following entry bindings are set up by the statement `j:eb:basic_bind Entry':
The left and right arrow keys move one character left or right.
Home moves to the beginning of the line
End moves to the end of the line
Control-i inserts a tab
Control-j inserts a newline
Return inserts a newline
Control-v pastes the current selection
Control-h deletes one character backwards
Delete deletes one character backwards
BackSpace deletes one character backwards
Any other key inserts its ASCII representation
Double¡clicking selects a word
Triple¡clicking selects the entire entry
Dragging the mouse left or right with Button 2 will cause the entry widget to scroll, but clicking (quickly) with Button 2 will paste the current X selection. (Thanks to Tom Phelps <phelps@cs.berkeley.edu> for code to implement this.)
The following text bindings are set up by the statement `j:tb:emacs_bind Text':
The arrow keys move one character or one line up, down, left or right. The concept of `line' used is that of the text widget (and of Emacs), so a long line that is wrapped in the text widget counts as one line. Also, lines with tabs in them are not currently treated properly.
Home moves to the beginning of the line
End moves to the end of the line
Next scrolls down one screenful. (Next is often labelled PageDown)
This requires that the widget be linked to a scrollbar.
Prior scrolls up one screenful. (Prior is often labelled PageUp)
This requires that the widget be linked to a scrollbar.
Control-i inserts a tab
Control-j inserts a newline
Return inserts a newline
Control-h deletes one character backwards
Delete deletes one character backwards
BackSpace deletes one character backwards
Control-p moves one line up (to the previous line)
Control-n moves one line down (to the next line)
Control-b moves one character to the left (backwards)
Control-f moves one character to the right (forwards)
Control-a moves to the beginning of the line
Control-e moves to the end of the line
Escape-b moves one word left (backwards)
Escape-f moves one word right (forwards)
Escape < moves to the top of the text
Escape > moves to the end of the text
Control-v scrolls down one screenful.
This requires that the widget be linked to a scrollbar.
Escape v scrolls up one screenful.
This requires that the widget be linked to a scrollbar.
Control-u generally, repeats the next key or key combination four times
Escape digit starts a numeric argument (to repeat the next key sequence)
Control-u digit starts a numeric argument (to repeat the next key sequence)
Control-q char inserts char literally, even if it's a control character
(There are some bugs in this.)
Control-d deletes one character to the right (forwards)
Escape Delete deletes one word to the left
Escape d deletes one word to the right
Control-k deletes (and remembers) the remainder of the line, as in Emacs
Control-w deletes and remembers the current selection
Control-y inserts text previously deleted by Control-k or Control-w
Control-@ set the Emacs `mark' (i.e., remember your current position)
Control-space set the Emacs `mark' (i.e., remember your current position)
Control-x Control-x
exchange the current insert position and the `mark'
(i.e., return to where you typed Control-@ or Control-space.)
(There are some bugs in this.)
Any other key inserts its ASCII representation
Dragging the mouse past the top or bottom edge of the widget with Button 1 will automatically scroll the widget as it extends the selection. (Thanks to Paul E. Raines <raines@cgibm1.slac.stanford.edu> for code to implement this.)
Dragging the mouse up or down with Button 2 will cause the text widget to scroll, but clicking (quickly) with Button 2 will paste the current X selection. (Thanks to Tom Phelps <phelps@ginkgo.cs.berkeley.edu> for code to implement this.)
Entry Bindings
The following entry bindings are set up by the statement `j:eb:emacs_bind Entry':
The left and right arrow keys move one character left or right.
Home moves to the beginning of the line
End moves to the end of the line
Control-i inserts a tab
Control-j inserts a newline
Return inserts a newline
Control-v pastes the current selection
Control-h deletes one character backwards
Delete deletes one character backwards
BackSpace deletes one character backwards
Control-b moves one character to the left (backwards)
Control-f moves one character to the right (forwards)
Control-a moves to the beginning of the line
Control-e moves to the end of the line
Escape-b moves one word left (backwards)
Escape-f moves one word right (forwards)
Control-d deletes one character to the right (forwards)
Escape Delete deletes one word to the left
Escape d deletes one word to the right
Control-k deletes to the end of the line
Control-w deletes the current selection
Any other key inserts its ASCII representation
Double¡clicking selects a word
Triple¡clicking selects the entire entry
Dragging the mouse left or right with Button 2 will cause the entry widget to scroll, but clicking (quickly) with Button 2 will paste the current X selection. (Thanks to Tom Phelps <phelps@ginkgo.cs.berkeley.edu> for code to implement this.)
qsection {Procedures to Set Bindings} {{These procedures provide the most important interface between your application and the jbindings.tcl library. They set up sets of bindings for entry and text widgets.
Obviously, you don't need to use j:eb:basic_bind or j:eb:emacs_bind if your application doesn't have any entry widgets, and you don't need to use j:tb:basic_bind or j:tb:emacs_bind if your application doesn't have any text widgets.
j:eb:basic_bind Entry set up basic bindings for entry widgets
j:eb:emacs_bind Entry set up Emacs bindings for entry widgets
j:tb:basic_bind Text set up basic bindings for text widgets
j:tb:emacs_bind Text set up Emacs bindings for text widgets
j:eb:basic_bind
Usage:
j:eb:basic_bind Entry
This procedure sets up the entry bindings described in the section Basic Bindings. In place of Entry, you can also specify the pathname of a particular entry widget, but this use hasn't been thoroughly tested and may not be reliable.
j:tb:basic_bind
Usage:
j:tb:basic_bind Text
This procedure sets up the text bindings described in the section Basic Bindings. In place of Text, you can also specify the pathname of a particular text widget, but this use hasn't been thoroughly tested and may not be reliable.
j:eb:emacs_bind
Usage:
j:eb:emacs_bind Entry
This procedure sets up the entry bindings described in the section Emacs Bindings. In place of Entry, you can also specify the pathname of a particular entry widget, but this use hasn't been thoroughly tested and may not be reliable.
j:tb:emacs_bind
Usage:
j:tb:emacs_bind Text
This procedure sets up the text bindings described in the section Emacs Bindings. In place of Text, you can also specify the pathname of a particular text widget, but this use hasn't been thoroughly tested and may not be reliable.
qsection {Publically¡Useful Text Procedures} {{These three procedures are used to mark the contents of a text widget as dirty (changed) or clean. In general, you will mark a text widget dirty whenever you change its contents, and clean when you save it; i.e., a text widget is dirty if it needs to be saved. All the jbindings.tcl procedures (and bindings) that alter a text widget mark it as dirty.
j:tb:mark_dirty mark text widget as dirty (modified)
j:tb:mark_clean mark text widget as clean (unmodified)
j:tb:is_dirty return 1 if text widget is dirty (modified) else 0
j:tb:mark_dirty
Usage:
j:tb:mark_dirty w
Arguments:
w is the widget to mark dirty
This procedure marks text widget w as dirty. This information can later be retrieved with j:tb:is_dirty.
j:tb:mark_clean
Usage:
j:tb:mark_clean w
Arguments:
w is the widget to mark clean
Example:
set file [open $filename w]
puts $file [.text get 1.0 end]
close $file
j:tb:mark_clean .text
This procedure marks text widget w as clean. This information can later be retrieved with j:tb:is_dirty.
j:tb:is_dirty
Usage:
j:tb:is_dirty w
Arguments:
w is the widget whose state you want to query
Example:
if [j:tb:is_dirty .main.t] {
if [j:confirm -text "Really quit without saving?"] {
exit 0
}
}
This procedure returns true (1) if widget w is currently marked dirty and false (0) otherwise. (It also returns false if w isn't a text widget whose bindings have been set up with j:tb:basic_bind or j:tb:emacs_bind.)